 /*******************************************************************************
  * Copyright (c) 2005 IBM Corporation and others.
  * All rights reserved. This program and the accompanying materials
  * are made available under the terms of the Eclipse Public License v1.0
  * which accompanies this distribution, and is available at
  * http://www.eclipse.org/legal/epl-v10.html
  *
  * Contributors:
  * IBM Corporation - initial API and implementation
  *******************************************************************************/
 package org.eclipse.core.internal.resources.mapping;

 import org.eclipse.core.resources.*;
 import org.eclipse.core.runtime.CoreException;
 import org.eclipse.core.runtime.IProgressMonitor;

 /**
  * A remote mapping context provides a model element with a view of the remote state
  * of local resources as they relate to a repository operation that is in
  * progress. A repository provider can pass an instance of this interface to a
  * model element when obtaining a set of traversals for a model element. This
  * allows the model element to query the remote state of a resource in order to
  * determine if there are resources that exist remotely but do not exist locally
  * that should be included in the traversal. The traversals should also be as
  * as possible to allow for optimization of remote operations.
  * <p>
  * This class may be subclassed by clients.
  * </p>
  *
  * @see ResourceMapping
  * @see ResourceMappingContext
  * @since 3.1
  */
 public abstract class RemoteResourceMappingContext extends ResourceMappingContext {

     /**
      * Refresh flag constant (bit mask value 0) indicating that no
      * additional refresh behavior is required.
      */
     public static final int NONE = 0;
     
     /**
      * Refresh flag constant (bit mask value 1) indicating that
      * the mapping will be making use of the contents of the files
      * covered by the traversals being refreshed.
      */
     public static final int FILE_CONTENTS_REQUIRED = 1;

     /**
      * Return whether the contents of the corresponding remote differs from the
      * content of the local file in the context of the current operation. By this
      * we mean that this method will return <code>true</code> if the remote contents differ
      * from the local contents and these remote contents would be fetched as part of the
      * operation associated with the context.
      * For instance, when updating the workspace to the latest remote state,
      * this method would only return <code>true</code> if the remote contentd have changed
      * since the last time the contents where updated. However, if replace the local contents,
      * the methdo would return <code>true</code> if either the remote contents or the lcoal contents
      * have changed.
      * <p>
      * This can be used by clients to determine if
      * they need to fetch the remote contents in order to determine if the
      * resources that constitute the model element are different in another
      * location. If the lcoa file exists and the remote file does not, then
      * the contents will be said to differ (i.e. <code>true</code> is returned).
      * </p>
      *
      * @param file the local file
      * @param monitor a progress monitor, or <code>null</code> if progress
      * reporting is not desired
      * @return whether the contents of the corresponding remote differs from the
      * content of the local file
      * @exception CoreException if the contents could not be compared. Reasons include:
      * <ul>
      * <li>The corresponding remote resource is not a container
      * (status code will be IResourceStatus.RESOURCE_WRONG_TYPE).</li>
      * </ul>
      */
     public abstract boolean contentDiffers(IFile file, IProgressMonitor monitor) throws CoreException;

     /**
      * Returns an instance of IStorage in order to allow the
      * caller to access the contents of the remote that corresponds to the given
      * local resource. If the remote file does not exist, <code>null</code> is
      * returned. The provided local file handle need not exist locally. A
      * exception is thrown if the corresponding remote resource is not a file.
      * <p>
      * This method may be long running as a server may need to be contacted to
      * obtain the contents of the file.
      * </p>
      *
      * @param file the local file
      * @param monitor a progress monitor, or <code>null</code> if progress
      * reporting is not desired
      * @return a storage that provides access to the contents of the local
      * resource's corresponding remote resource. If the remote file
      * does not exist, <code>null</code> is returned
      * @exception CoreException if the contents could not be fetched. Reasons include:
      * <ul>
      * <li>The corresponding remote resource is not a container
      * (status code will be IResourceStatus.RESOURCE_WRONG_TYPE).</li>
      * </ul>
      */
     public abstract IStorage fetchContents(IFile file, IProgressMonitor monitor) throws CoreException;

     /**
      * Returns the list of member resources whose corresponding remote resources
      * are members of the corresponding remote resource of the given local
      * container. The container need not exist locally and the result may
      * include entries that do not exist locally and may not include all local
      * children. An empty list is returned if the remote resource which
      * corresponds to the container is empty. A <code>null</code> is
      * returned if the remote does not exist. An exception is thrown if the
      * corresponding remote is not capable of having members.
      * <p>
      * This method may be long running as a server may need to be contacted to
      * obtain the members of the containers corresponding remote resource.
      * </p>
      *
      * @param container the local container
      * @param monitor a progress monitor, or <code>null</code> if progress
      * reporting is not desired
      * @return a list of member resources whose corresponding remote resources
      * are members of the remote counterpart of the given container or
      * <code>null</code> if the remote does not exist.
      * @exception CoreException if the members could not be fetched. Reasons include:
      * <ul>
      * <li>The corresponding remote resource is not a container
      * (status code will be IResourceStatus.RESOURCE_WRONG_TYPE).</li>
      * </ul>
      */
     public abstract IResource[] fetchMembers(IContainer container, IProgressMonitor monitor) throws CoreException;

     /**
      * Refresh the known remote state for any resources covered by the given traversals.
      * Clients who require the latest remote state should invoke this method before
      * invoking any others of the class. Mappings can use this method as a hint to the
      * context provider of which resources will be required for the mapping to generate
      * the proper set of traversals.
      * <p>
      * Note that this is really only a hint to the context provider.
      * It is up to implementors to decide, based on the provided traversals, how to efficiently
      * perform the refresh. In the ideal case, calls to {@link #contentDiffers} and {@link #fetchMembers}
      * would not need to contact the server after a call to a refresh with appropriate traversals. Also, ideally,
      * if {@link #FILE_CONTENTS_REQUIRED} is on of the flags, then the contents for these files will be chached as efficiently
      * as possible so that calls to {@link #fetchContents} will also not need to contact the server. This may
      * not be possible for all context providers, so clients cannot assume that the above mentioed methods will not
      * be long running. It is still advisably for clients to call {@link #refresh} with as much details
      * as possible since, in the case where a provider is optimized performance will be much better.
      * </p>
      *
      * @param traversals the resource traversals which indicate which resources are to be refreshed
      * @param flags additional refresh behavior. For instance, if <code>FILE_CONTENTS_REQUIRED</code>
      * is one of the flags, this indicates that the client will be accessing the contents of
      * the files covered by the traversals. <code>NONE</code> shoudl be used when no additional
      * behavior is required
      * @param monitor a progress monitor, or <code>null</code> if progress
      * reporting is not desired
      * @exception CoreException if the members could not be fetched.
      */
     public abstract void refresh(ResourceTraversal[] traversals, int flags, IProgressMonitor monitor) throws CoreException;

 }

